home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Programming / ixemul / sdk / man / cat3 / recno.0 < prev    next >
Encoding:
Text File  |  1998-06-15  |  7.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. RECNO(3)                                                 RECNO(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        recno - record number database access method
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  12.        ##iinncclluuddee <<ddbb..hh>>
  13.  
  14. DDEESSCCRRIIPPTTIIOONN
  15.        The  routine  _d_b_o_p_e_n  is the library interface to database
  16.        files.  One of the supported file formats is record number
  17.        files.   The  general  description  of the database access
  18.        methods is in _d_b_o_p_e_n(3), this manual page  describes  only
  19.        the recno specific information.
  20.  
  21.        The  record  number  data  structure is either variable or
  22.        fixed-length  records  stored  in  a   flat-file   format,
  23.        accessed  by  the logical record number.  The existence of
  24.        record number five implies the existence  of  records  one
  25.        through four, and the deletion of record number one causes
  26.        record number five to be renumbered to record number four,
  27.        as  well  as the cursor, if positioned after record number
  28.        one, to shift down one record.
  29.  
  30.        The recno access method specific data  structure  provided
  31.        to  _d_b_o_p_e_n  is  defined in the <db.h> include file as fol-
  32.        lows:
  33.  
  34.        typedef struct {
  35.               u_long flags;
  36.               u_int cachesize;
  37.               u_int psize;
  38.               int lorder;
  39.               size_t reclen;
  40.               u_char bval;
  41.               char *bfname;
  42.        } RECNOINFO;
  43.  
  44.        The elements of this structure are defined as follows:
  45.  
  46.        flags  The flag value is specified by _o_r'ing  any  of  the
  47.               following values:
  48.  
  49.               R_FIXEDLEN
  50.                      The   records  are  fixed-length,  not  byte
  51.                      delimited.   The  structure  element  _r_e_c_l_e_n
  52.                      specifies  the length of the record, and the
  53.                      structure element _b_v_a_l is used  as  the  pad
  54.                      character.   Any  records, inserted into the
  55.                      database, that are less  than  _r_e_c_l_e_n  bytes
  56.                      long are automatically padded.
  57.  
  58.               R_NOKEY
  59.                      In  the  interface  specified by _d_b_o_p_e_n, the
  60.                      sequential record retrieval  fills  in  both
  61.  
  62.  
  63.  
  64.                          August 18, 1994                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RECNO(3)                                                 RECNO(3)
  71.  
  72.  
  73.                      the  caller's  key  and data structures.  If
  74.                      the R_NOKEY flag is  specified,  the  _c_u_r_s_o_r
  75.                      routines are not required to fill in the key
  76.                      structure.   This  permits  applications  to
  77.                      retrieve records at the end of files without
  78.                      reading all of the intervening records.
  79.  
  80.               R_SNAPSHOT
  81.                      This flag requires that a  snapshot  of  the
  82.                      file be taken when _d_b_o_p_e_n is called, instead
  83.                      of permitting any unmodified records  to  be
  84.                      read from the original file.
  85.  
  86.        cachesize
  87.               A  suggested  maximum size, in bytes, of the memory
  88.               cache.  This value is oonnllyy advisory, and the access
  89.               method  will allocate more memory rather than fail.
  90.               If _c_a_c_h_e_s_i_z_e is  0 (no size is specified) a default
  91.               cache is used.
  92.  
  93.        psize  The recno access method stores the in-memory copies
  94.               of its records in a btree.  This value is the  size
  95.               (in  bytes)  of  the  pages  used for nodes in that
  96.               tree.  If _p_s_i_z_e is 0 (no page size is specified)  a
  97.               page  size  is  chosen based on the underlying file
  98.               system I/O  block  size.   See  _b_t_r_e_e(3)  for  more
  99.               information.
  100.  
  101.        lorder The  byte order for integers in the stored database
  102.               metadata.  The number should represent the order as
  103.               an  integer; for example, big endian order would be
  104.               the number 4,321.  If _l_o_r_d_e_r  is  0  (no  order  is
  105.               specified) the current host order is used.
  106.  
  107.        reclen The length of a fixed-length record.
  108.  
  109.        bval   The delimiting byte to be used to mark the end of a
  110.               record for variable-length  records,  and  the  pad
  111.               character for fixed-length records.  If no value is
  112.               specified, newlines (``\n'') are used to  mark  the
  113.               end  of  variable-length  records  and fixed-length
  114.               records are padded with spaces.
  115.  
  116.        bfname The recno access method stores the in-memory copies
  117.               of  its records in a btree.  If bfname is non-NULL,
  118.               it specifies the name of  the  btree  file,  as  if
  119.               specified  as the file name for a dbopen of a btree
  120.               file.
  121.  
  122.        The data part of the  key/data  pair  used  by  the  recno
  123.        access  method  is  the same as other access methods.  The
  124.        key is different.  The _d_a_t_a field of the key should  be  a
  125.        pointer  to  a memory location of type _r_e_c_n_o___t, as defined
  126.        in the <db.h> include file.  This  type  is  normally  the
  127.  
  128.  
  129.  
  130.                          August 18, 1994                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. RECNO(3)                                                 RECNO(3)
  137.  
  138.  
  139.        largest  unsigned integral type available to the implemen-
  140.        tation.  The _s_i_z_e field of the key should be the  size  of
  141.        that type.
  142.  
  143.        Because  there  can  be  no  meta-data associated with the
  144.        underlying recno access method files, any changes made  to
  145.        the default values (e.g. fixed record length or byte sepa-
  146.        rator value) must be explicitly specified  each  time  the
  147.        file is opened.
  148.  
  149.        In the interface specified by _d_b_o_p_e_n, using the _p_u_t inter-
  150.        face to create a new record will  cause  the  creation  of
  151.        multiple,  empty records if the record number is more than
  152.        one greater than  the  largest  record  currently  in  the
  153.        database.
  154.  
  155. EERRRROORRSS
  156.        The  _r_e_c_n_o  access  method routines may fail and set _e_r_r_n_o
  157.        for any of the errors specified for  the  library  routine
  158.        _d_b_o_p_e_n(3) or the following:
  159.  
  160.        [EINVAL]
  161.               An  attempt  was  made  to add a record to a fixed-
  162.               length database that was too large to fit.
  163.  
  164. SSEEEE AALLSSOO
  165.        _b_t_r_e_e(3), _d_b_o_p_e_n(3), _h_a_s_h(3), _m_p_o_o_l(3)
  166.  
  167.        _D_o_c_u_m_e_n_t  _P_r_o_c_e_s_s_i_n_g  _i_n  _a  _R_e_l_a_t_i_o_n_a_l  _D_a_t_a_b_a_s_e  _S_y_s_t_e_m,
  168.        Michael   Stonebraker,   Heidi  Stettner,  Joseph  Kalash,
  169.        Antonin  Guttman,  Nadene  Lynn,  Memorandum  No.  UCB/ERL
  170.        M82/32, May 1982.
  171.  
  172. BBUUGGSS
  173.        Only big and little endian byte order is supported.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                          August 18, 1994                        3
  197.  
  198.  
  199.